More mkdocs options#45
Conversation
damskii9992
added
[scope] enhancement
| inventories: | ||
| - url: https://scipp.github.io/objects.inv | ||
| - url: https://numpy.org/doc/stable/objects.inv | ||
| - url: https://easyscience.github.io/core/2.3.1/objects.inv |
There was a problem hiding this comment.
Could we avoid pinning the core inventory to 2.3.1 here? Since NumPy uses stable and Scipp exposes an unversioned inventory, the core URL should ideally be something like https://easyscience.github.io/core/latest/objects.inv once core publishes that alias.
It may also be worth adding a pixi.toml docs task in core to build and verify objects.inv.
There was a problem hiding this comment.
I think we can solve this issue by changing the alias-type of mike. You've currently set it to "redirect" in the pixi.toml command, using "symlink" or "copy" should make it work (i think). According to Claude, symlinks aren't treated well by github pages though, so maybe we need to use "copy" for this to work . . .
There was a problem hiding this comment.
Great, thanks. I used --alias-type copy and verified the behavior on peasy-lib: objects.inv is now published under the latest/ alias as well.
So I switched the core inventory URL in the template from the pinned 2.3.1 path to https://easyscience.github.io/core/latest/objects.inv.
2 participants
This PR adds more quality-of-life stuff to the documentation:
Relative_crossrefs and scoped_crossrefs allows links within docstrings to other methods, like [name][.method] will provide a link within the docs to the method .method of the class, see https://mkdocstrings.github.io/python/usage/configuration/docstrings/#scoped_crossrefs
for information on how to use it.
I also add a filter which is the default filter minus repr and dir since i assume we don't want those methods in our api-reference.
Lastly i add inventories to numpy and scipp. This allows mkdocs to provide links to these libraries whenever their types are encountered and it allows easy references like [array][scipp.array] in the documentation.